<html>
  <head>
    <title>ShortcutRecorder class documentation</title>
<style>
#cocoa-class-docs {
font: 12px lucida grande, geneva, helvetica, arial, sans-serif;
}
#cocoa-class-docs a {
    text-decoration: none;
}
#cocoa-class-docs p {
    margin-top: 0;
    margin-bottom: 10px;
}
#cocoa-class-docs CODE {
	FONT-SIZE: 11px; FONT-FAMILY: monaco, courier, monospace; }
#cocoa-class-docs h1	{
	margin-top: 1em;
	margin-bottom: 25px;
	font: bold 30px lucida grande, geneva, helvetica, arial, sans-serif;
	color: #000;
	}
#cocoa-class-docs h2	{
	margin-top: 2.5em;
	font-size: 24px;
	color: #000;
	padding-bottom: 2px; border-bottom: 1px solid black;
	}
#cocoa-class-docs h3	{
	margin-top: 2em;
	margin-bottom: .5em;
	font-size: 19px;
	color: #000;
	}
#cocoa-class-docs h3.tight {
	margin-top: 3em;
	margin-bottom: -.25em;
	font-size: 19px;
	color: #000;
	}
#cocoa-class-docs h3.verytight {
	margin-top: 1em;
	margin-bottom: -.25em;
	font-size: 19px;
	color: #000;
	}

#cocoa-class-docs dl {
    margin-top: 0;
}

#cocoa-class-docs h3 + dl {
    margin-top: 0.5em;
}
	
#cocoa-class-docs .method-listing h3 {
	margin-top: 3em;
	margin-bottom: -0.25em;
	font-size: 19px;
	color: #000;
}

#cocoa-class-docs .method-listing h3 + p {
    margin-top: 13px;
    margin-bottom: 10px;
}

#cocoa-class-docs .method-listing p dfn {
    FONT-SIZE: 11px; FONT-FAMILY: monaco, courier, monospace;
}

#cocoa-class-docs .method-listing var {
    font-family: "lucida grande", geneva, helvetica, arial, sans-serif;
    font-size: 12px;
    font-style: italic;
}

#cocoa-class-docs .method-listing h4 {
    margin-top: 1.5em;
    margin-right: 0px;
    margin-bottom: 2px;
    margin-left: 0px;
    padding: 0;
	font: bold 13px lucida grande, geneva, helvetica, arial, sans-serif;

}

#cocoa-class-docs .method-toc ul {
    list-style: none outside; 
    margin-left: 30px; margin-bottom: 0px;
    margin-top: 10px;
    padding: 0px;
    padding-bottom: 12px;
    padding-left: 6px;
	}
#cocoa-class-docs .method-toc ul li {
	margin: 2px 0 0 0;
	}
	
#cocoa-class-docs .method-toc ul li a {
    margin-left: 5px; 
    display: block; 
    padding: 0px 5px 0px 5px;
}

#cocoa-class-docs ul.see-also {
    list-style-type: none;
    margin: 0px 0px -10px 0px;
    padding: 0px 0px 12px 6px;
}

#cocoa-class-docs ul.see-also li {
    margin: 2px 0px 0px -6px;
}

.specbox {
border-top: 1px solid rgb(145, 150, 153);
border-left: 1px solid rgb(145, 150, 153);
border-right: 1px solid rgb(145, 150, 153);
margin-bottom: 10px;
margin-left: 1em;
}

.specbox tr, .specbox tr + tr + tr {
background-color: rgb(240, 245, 249)
}

.specbox tr + tr, .specbox tr + tr + tr + tr {
background-color: white;
}

.specbox td {
    padding: 8px;
    font-size: 12px;
    text-align: left;
    vertical-align: top;
    border-bottom: 1px solid rgb(145, 150, 153);
}


</style>
  </head>
  <body>



<div id="cocoa-class-docs">
<h1>ShortcutRecorder</h1>
<table cellspacing="0" class="specbox">
<tr><td scope="row"><b><span style="white-space: nowrap;">Inherits from</span></b></td><td><div style="margin-bottom:1px"><a href="http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSControl.html#//apple_ref/occ/cl/NSControl" target="_top">NSControl</a> : <a href="http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSView.html#//apple_ref/occ/cl/NSView" target="_top">NSView</a> : <a href="http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSResponder.html#//apple_ref/occ/cl/NSResponder" target="_top">NSResponder</a> : <a href="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSObject.html#//apple_ref/occ/cl/NSObject" target="_top">NSObject</a></div></td></tr>
<tr><td scope="row"><b><span style="white-space: nowrap;">Conforms to</span></b></td><td><div style="margin-bottom:1px">
<span class="content_text"><a href="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Protocols/NSCoding.html#//apple_ref/occ/intf/NSCoding" target="_top">NSCoding (NSResponder)</a></span><br>

<span class="content_text"><a href="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Protocols/NSObjectProtocol.html#//apple_ref/occ/intf/NSObject" target="_top">NSObject (NSObject)</a></span><br>
</div></td></tr>
<tr><td scope="row"><b><span style="white-space: nowrap;">Declared in</span></b></td><td><div style="margin-bottom:1px"><span class="content_text">ShortcutRecorder.h</span><br>
</td></tr></table><br>


<h2>Class Description</h2>

<p><code>ShortcutRecorder</code> is a subclass of <code>NSControl</code> that intercepts keyboard events.</p>
<p><code>ShortcutRecorder</code> uses <code>ShortcutRecorderCell</code> to implement its user interface and main functions.</p>
<p><code>ShortcutRecorderCell</code> internally stores the current key combination in its own <code>KeyCombo</code> structure. This structure stores the virtual key code in a member named <code>code</code> and the key mask (Cocoa-style) in a member named <code>flags</code>. <code>ShortcutRecorderCell</code> provides two methods for conversion (both ways) between Cocoa-style key mask flags and Carbon-style.</p>
<p>Before <code>ShortcutRecorder</code> sets the key combination you enter, it will make a bona fide attempt to make sure the key combination isn't already in use. It will check menu items contained in menus in the menu bar and system-wide shortcuts for any chance of collision, and if your delegate answers to a specific method, it will also check with your delegate for clearance. Your delegate can be a good way to check for shortcuts assigned to menu items in pop up menus, registered "hotkeys" and so on.</p>
<p>Additionally, you can provide, separately, key masks for allowed modifier keys and for required modifier keys. By not including a modifier in the allowed key mask, it's effectively prohibited, and by including a modifier in the required key mask, it's effectively active on all key combinations by default. The required key mask bests the allowed key mask - the required key mask is applied at the very end, after the modifiers not allowed have been filtered out.</p>
<p>In order to get the key combination when it is changed, you must assign a delegate to <code>ShortcutRecorder</code>. If using it directly, instead assign a delegate to <code>ShortcutRecorderCell</code>, which has similar delegate methods. </p>
<p><code>ShortcutRecorder</code> will not register "hotkeys" for you - it will do nothing outside of keeping the key combination entered into it and make sure it passes the constraints you can set on it (and also some of which you can't - checking for collisions with menu items and system-wide shortcuts).</p>

<h2>Defined Structures</h2><div class="method-listing">
<h3><a name="shortcutrecorder_struct_KeyCombo"></a>KeyCombo</h3>
<dl><dt><dfn>unsigned int <var>flags</var></dfn></dt><dd>The Cocoa-style modifier key mask. Set this to <code>0</code> for no flags.</dd>
<dt><dfn>signed short <var>code</var></dfn></dt><dd>The virtual key code. Set to <code>-1</code> for no code.</dd>
</dl>
<h4>Discussion</h4>
<p><code>KeyCombo</code> is defined in ShortcutRecorderCell.h. Both member fields use the formats used in <a href="http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSEvent.html#//apple_ref/occ/cl/NSEvent"><code>NSEvent</code></a>.</p>

</div>


<h2>Methods by Task</h2><div class="method-toc">

<h3>Saving and restoring state</h3><ul>
<li><a href="#shortcutrecorder_autosaveName"><code>- autosaveName</code></a></li>
<li><a href="#shortcutrecorder_setAutosaveName_"><code>- setAutosaveName:</code></a></li></ul>

<h3>Key combination control</h3><ul>
<li><a href="#shortcutrecorder_keyCombo"><code>- keyCombo</code></a></li>
<li><a href="#shortcutrecorder_setKeyCombo_"><code>- setKeyCombo:</code></a></li></ul>

<h3>Modifier flag control</h3><ul>
<li><code><a href="#shortcutrecorder_allowedFlags">- allowedFlags</code></a></li>
<li><code><a href="#shortcutrecorder_setAllowedFlags_">- setAllowedFlags:</code></a></li>
<li><code><a href="#shortcutrecorder_requiredFlags">- requiredFlags</code></a></li>
<li><code><a href="#shortcutrecorder_setRequiredFlags_">- setRequiredFlags:</code></a></li></ul>

<h3>Displaying the key combination</h3><ul>
<li><code><a href="#shortcutrecorder_keyComboString">- keyComboString</code></a></li></ul>

<h3>Conversion of flags</h3><ul>
<li><code><a href="#shortcutrecorder_cocoaToCarbonFlags_">- cocoaToCarbonFlags:</code></a></li>
<li><code><a href="#shortcutrecorder_carbonToCocoaFlags_">- carbonToCocoaFlags:</code></a></li></ul>

<h3>Setting the delegate</h3><ul>
<li><code><a href="#shortcutrecorder_delegate">- delegate</a></code></li>
<li><code><a href="#shortcutrecorder_setDelegate_">- setDelegate:</a></code></li></ul>
</div>

<h2>Instance Methods</h2><div class="method-listing">

<h3><a name="shortcutrecorder_allowedFlags"></a>allowedFlags</h3>
<p>Returns the allowed flags of the receiver.</p>
<p><dfn>- (unsigned int)allowedFlags</dfn></p>
<h4>Return Value</h4>
<p>Returns the allowed flags (Cocoa-style) of the receiver.</p>
<h4>Discussion</h4>
<p><code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_setAllowedFlags_"><code>- setAllowedFlags:</code></a></li></ul>


<h3><a name="shortcutrecorder_autosaveName"></a>autosaveName</h3>
<p>Returns the autosave name of the receiver under which it is automatically saved. </p>
<p><dfn>- (<a href="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSString.html#//apple_ref/occ/cl/NSString" target="_top">NSString</a> *)autosaveName</dfn></p>
<h4>Return Value</h4>
<p>If no name has been set, this method returns <code>nil</code>.</p>
<h4>Discussion</h4>
<p><code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_setAutosaveName_"><code>- setAutosaveName:</code></a></li></ul>


<h3><a name="shortcutrecorder_carbonToCocoaFlags_"></a>carbonToCocoaFlags:</h3>
<p>Returns <var>carbonFlags</var> as Cocoa-style flags.</p>
<p><dfn>- (unsigned int)carbonToCocoaFlags:(unsigned int)<var>carbonFlags</var></dfn></p>
<h4>Parameters</h4>
<dl><dt><var>carbonFlags</var></dt>
<dd>The key mask to convert.</dd>
</dl>
<h4>Return Value</h4>
<p>Returns <var>carbonFlags</var> as Cocoa-style flags.</p>
<h4>Discussion</h4>
<p><code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_cocoaToCarbonFlags_"><code>- cocoaToCarbonFlags:</code></a></li></ul>


<h3><a name="shortcutrecorder_cocoaToCarbonFlags_"></a>cocoaToCarbonFlags:</h3>

<p>Returns <var>cocoaFlags</var> as Carbon-style flags.</p>

<p><dfn>- (unsigned int)cocoaToCarbonFlags:(unsigned int)<var>cocoaFlags</var></dfn></p>
<h4>Parameters</h4>
<dl><dt><var>cocoaFlags</var></dt>
<dd>The key mask to convert.</dd>
</dl>
<h4>Return Value</h4><p>Returns <var>cocoaFlags</var> as Cocoa-style flags.</p>
<h4>Discussion</h4><p><code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_carbonToCocoaFlags_"><code>- carbonToCocoaFlags:</code></a></li>
</ul>


<h3><a name="shortcutrecorder_delegate"></a>delegate</h3>
<p>Returns the receiver's delegate.</p>
<p><dfn>- (id)delegate</dfn></p>
<h4>Return Value</h4><p>Returns the receiver's delegate, or <code>nil</code> if no delegate has been set.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_setDelegate_"><code>- setDelegate:</code></a></li>
</ul>

<h3><a name="shortcutrecorder_keyCombo"></a>keyCombo</h3>
<p>Returns the currently stored key combo.</p>
<p><dfn>- (<a href="#shortcutrecorder_struct_KeyCombo">KeyCombo</a>)keyCombo</dfn></p>
<h4>Return Value</h4><p>Returns the currently stored key combo (a <code>KeyCombo</code> structure).</p>
<h4>Discussion</h4><p><code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_setKeyCombo_"><code>- setKeyCombo:</code></a></li>
</ul>


<h3><a name="shortcutrecorder_keyComboString"></a>keyComboString</h3>
<p>Returns the receiver's current key combo, formatted in a way that's presentable in the UI.</p>
<p><dfn>- (<a href="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSString.html#//apple_ref/occ/cl/NSString" target="_top">NSString</a> *)keyComboString</dfn></p>
<h4>Return Value</h4><p>Returns the formatted string of the receiver's current key combo. If no valid key combo has been set, this method returns <code>nil</code>.</p>
<h4>Discussion</h4><p>This formats the key combo in a way that's presentable in the UI as-is. This means, for example, presenting the modifier keys, special keys (like Escape) and the arrow keys with their respective "fancy glyphs". <code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_keyCombo_"><code>- keyCombo:</code></a></li>
</ul>


<h3><a name="shortcutrecorder_requiredFlags"></a>requiredFlags</h3>

<p>Returns the required flags of the receiver.</p>

<p><dfn>- (unsigned int)requiredFlags</dfn></p>

<h4>Return Value</h4><p>Returns the allowed flags (Cocoa-style) of the receiver.</p>
<h4>Discussion</h4><p>By default, no modifier flag is required. <code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_setRequiredFlags_"><code>- setRequiredFlags:</code></a></li>
</ul>


<h3><a name="shortcutrecorder_setAllowedFlags_"></a>setAllowedFlags:</h3>

<p>Sets the receiver's allowed flags to <var>flags</var>.</p>

<p><dfn>- (void)setAllowedFlags:(unsigned int)<var>flags</var></dfn></p>

<h4>Parameters</h4>
<dl><dt><var>flags</var></dt>
<dd>The new Cocoa-style key mask.</dd>
</dl>
<h4>Discussion</h4><p><code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_allowedFlags"><code>- allowedFlags</code></a></li>
</ul>


<h3><a name="shortcutrecorder_setAutosaveName_"></a>setAutosaveName:</h3>

<p>Changes the name of the receiver under which it is automatically saved.</p>

<p><dfn>- (void)setAutosaveName:(<a href="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSString.html#//apple_ref/occ/cl/NSString" target="_top">NSString</a> *)aName</dfn></p>

<h4>Parameters</h4>
<dl><dt><var>aName</var></dt>
<dd>The new autosave name.</dd>
</dl>

<h4>Discussion</h4>
<p>Sets the receiver's autosave name to <var>aName</var>, or clears it if <var>aName</var> is <code>nil</code> or <code>@""</code>. <code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_autosaveName"><code>- autosaveName</code></a></li>
</ul>


<h3><a name="shortcutrecorder_setDelegate_"></a>setDelegate:</h3>
<p>Sets the receiver's delegate.</p>
<p><dfn>- (void)setDelegate:(id)<var>aDelegate</var></dfn></p>

<h4>Parameters</h4>
<dl><dt><var>aDelegate</var></dt>
<dd>The new delegate.</dd>
</dl>

<h4>Discussion</h4>
<p>Sets the receiver's delegate to <var>aDelegate</var>, or clears it if <var>aDelegate</var> is <code>nil</code>.</p>
<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_delegate"><code>- delegate</code></a></li>
</ul>

<h3><a name="shortcutrecorder_setKeyCombo_"></a>setKeyCombo:</h3>

<p>Sets the receiver's key combo to <var>aKeyCombo</var> in consideration of the allowed and required flags.</p>
<p><dfn>- (void)setKeyCombo:(<a href="#shortcutrecorder_struct_KeyCombo">KeyCombo</a>)<var>aKeyCombo</var></dfn></p>

<h4>Parameters</h4>
<dl><dt><var>aKeyCombo</var></dt>
<dd>The new key combo.</dd>
</dl>
<h4>Discussion</h4><p><code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>

<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_keyCombo"><code>- keyCombo</code></a></li>
<li><a href="#shortcutrecorder_allowedFlags"><code>- allowedFlags</code></a></li>
<li><a href="#shortcutrecorder_requiredFlags"><code>- requiredFlags</code></a></li>
</ul>


<h3><a name="shortcutrecorder_setRequiredFlags_"></a>setRequiredFlags:</h3>

<p>Sets the receiver's required flags to <var>flags</var>.</p>

<p><dfn>- (void)setRequiredFlags:(unsigned int)<var>flags</var></dfn></p>

<h4>Parameters</h4>
<dl><dt><var>flags</var></dt>
<dd>The new Cocoa-style key mask.</dd>
</dl>

<h4>Discussion</h4><p><code>ShortcutRecorder</code> implements this method by invoking the same method in its <code>ShortcutRecorderCell</code> object.</p>

<h4>See also:</h4><ul class="see-also">
<li><a href="#shortcutrecorder_requiredFlags"><code>- requiredFlags</code></a></li>
</ul>

</div>

<h2>Delegate Methods by Task</h2><div class="method-toc">
<h3>Delegate methods</h3><ul>
<li><a href="#shortcutrecorder_shortcutRecorder_isKeyCode_andFlagsTaken_reason_"><code>- shortcutRecorder:isKeyCode:andFlagsTaken:reason:</code></a></li>
<li><a href="#shortcutrecorder_shortcutRecorder_keyComboDidChange_"><code>- shortcutRecorder:keyComboDidChange:</code></a></li></ul>
</div>

<h2>Delegate Methods</h2><div class="method-listing">

<h3><a name="shortcutrecorder_shortcutRecorder_keyComboDidChange_"></a>shortcutRecorder:keyComboDidChange:</h3>
<p>Informs the delegate that the key combo has changed.</p>
<p><dfn>- (void)shortcutRecorder:(ShortcutRecorder *)<var>aRecorder</var> keyComboDidChange:(<a href="#shortcutrecorder_struct_KeyCombo">KeyCombo</a>)<var>newKeyCombo</var></dfn></p>
<h4>Parameters</h4>
<dl>
<dt><var>aRecorder</var></dt>
<dd>The <code>ShortcutRecorder</code> having been changed.</dd>
<dt><var>newKeyCombo</var></dt>
<dd>The new key combination in <code>KeyCombo</code> form.</dd>
</dl>

<h3><a name="shortcutrecorder_shortcutRecorder_isKeyCode_andFlagsTaken_reason_"></a>shortcutRecorder:isKeyCode:andFlagsTaken:reason:</h3>
<p>Called before the receiver verifies its key combo system wide and in all menus.</p>
<p><dfn>- (BOOL)shortcutRecorder:(ShortcutRecorder *)<var>aRecorder</var> isKeyCode:(unsigned short)<var>keyCode</var> andFlagsTaken:(unsigned int)<var>flags</var> reason:(<a href="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSString.html#//apple_ref/occ/cl/NSString" target="_top">NSString</a> **)<var>aReason</var></dfn></p>
<h4>Parameters</h4>
<dl>
<dt><var>aRecorder</var></dt>
<dd>The <code>ShortcutRecorder</code> about to be changed.</dd>
<dt><var>keyCode</var></dt>
<dd>The virtual key code in the proposed key combination.</dd>
<dt><var>flags</var></dt>
<dd>The Cocoa-style modifier key mask in the proposed key combination.</dd>
<dt><var>aReason</var></dt>
<dd>The reason, as a pointer to an <a href="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSString.html#//apple_ref/occ/cl/NSString" target="_top"><code>NSString</code></a>, why the key combination is occupied.</dd>
</dl>
<h4>Return Value</h4>
<p>Reports whether the <code>ShortcutRecorder</code> should accept the key combination or not. If not, an alert will be displayed with the contents in <var>aReason</var>.</p>
<h4>Discussion</h4>
<p>Return <code>YES</code> to sign a collision (an alert will be shown with the text in <var>aReason</var>), <code>NO</code> to continue the chain of verification.</p>

</div>

  </body>
</html> 